Integrations SDK

The Integrations SDK is the toolkit and contract for building custom modules that extend the Istari Digital Platform. A module packages one or more functions that an Istari Digital agent can execute as part of a user job — typically wrapping a CAD tool, simulation solver, in-house script, or external service so it becomes a first-class platform capability.

This section is for integration developers — designing, implementing, validating, and packaging modules. The Istari Digital CLI is the tool used at every step of the workflow; this section explains the contract, the authoring framework, and the end-to-end workflow that the CLI supports.

Key features

• Language-agnostic, file-based contract. A module is a directory containing a module_manifest.json and the executable that runs your function. The agent passes inputs and outputs as JSON files on disk — your function can be written in any language. See Module concepts.
• Two authoring paths. Hand-roll a manifest plus any executable (shell, Go, .NET, …) for maximum flexibility, or scaffold a structured Python module with stari module scaffold --type python-module to get a Pydantic-typed function framework, a function registry, build scripts, hooks, and pre-built templates out of the box.
• Function variants for OS and tool versions. A single module can declare multiple variants of the same function targeting different operating systems (Windows 10/11, Ubuntu 20.04/22.04/24.04, RHEL 8/9) or different tool versions; the platform resolves which to invoke at runtime.
• Manifest-driven publishing. A versioned manifest declares everything the platform needs — entrypoint, run command, function schemas, dependencies, supported OS, build / test / install / clean scripts.
• Scoped naming. Modules and functions use a @scope:name convention. @istari is reserved for first-party integrations; pick your own scope (e.g. @acme_corp:cad_tools) for internal or distributed modules.

Authoring workflow

The end-to-end module-authoring workflow:

1. Scaffold or hand-roll the module structure. For Python: stari module scaffold <name> --type python-module generates a project with Pydantic Input / Output types, a function registry, function templates for common patterns (1-input → 1-output, parameter sweep, OIDC auth, etc.), pyproject.toml build configuration, hooks, and tests. For other languages: create a directory with module_manifest.json and your executable.
2. Define the function schema in the manifest. Inputs declare types (@string, @number, @object, validation types like @extension:txt); outputs declare files or directories. Export the JSON schema with stari schemas get function_input for editor tooling or LLM-assisted editing.
3. Implement the function. Read the input JSON, run your logic, write the output JSON. The Python scaffold provides a registry-based dispatch and Pydantic validation; non-Python modules parse --input-file and write --output-file directly.
4. Validate the manifest — stari module lint module_manifest.json. If it lints, it's publishable.
5. Generate sample inputs and outputs — stari function generate test_files --function @scope:<fn> produces realistic JSON files for local testing. See Function test file generation.
6. Run the manifest's scripts — stari module run build, stari module run test_unit, stari module run install, stari module run clean. The Python scaffold wires these to Poetry; non-Python modules wire them however they like.
7. Package — for Python, build a self-contained binary with PyInstaller (or your preferred bundler) and zip the result. For other languages, zip the directory.
8. Publish to the registry — stari client publish module_manifest.json. See the Istari Digital CLI for credentials configuration.
9. Grant access — through the platform UI, assign the published module to users or pools so they can run it.

After publishing, deploying the module onto agent hosts (stari module install, stari module update) is documented in the CLI.

What's in this section

Page	What it covers
Module concepts	Modules, functions, manifests, the file-based agent contract, lifecycle, package layout, function variants, scopes, and best practices.
Authoring with the CLI	How stari supports module authors — scaffolding, manifest creation, schema generation, script execution, linting, mock test data.
[Module Manifest API reference](./API Reference/01-api-reference.md)	Every manifest field — required vs optional, types, semver-aware version ranges, function info, scripts, dependencies, enums.
[Manifest examples](./API Reference/02-manifest-examples.md)	Worked examples of entrypoint, run_command, function schemas, input / output / config file payloads.

tip

For a guided first build:

• Integration 301 — First module (shell): hand-rolled manifest plus a shell script. Teaches the file contract end-to-end without a Python framework.
• Integration 302 — Build a Python module: uses stari module scaffold --type python-module to generate a Pydantic-typed framework, then compiles to a standalone binary with PyInstaller.